% Manual for the STM program
%
% To generate the printed version:
%
% latex stm
% latex stm
% [ dvips stm ] 
%
%   Pablo Ordejon and Nicolas Lorente
%   November 2004
%   Alberto Garcia, August 2009
%   Alberto Garcia, March-June 2019


\documentstyle[11pt]{article}

\tolerance 10000
\textheight 22cm
\textwidth 16cm
\oddsidemargin 1mm
\topmargin -15mm

\baselineskip=14pt
\parskip 5pt
\parindent 1em

\begin{document}

% TITLE PAGE --------------------------------------------------------------

\begin{titlepage}

\begin{center}

\vspace{1cm}

{\huge {\sc User's Guide}}

\vspace{4cm}

{\Huge {\bf {\sc wfs2ldos} 2.0} }

\vspace{0.5 cm}

{\Large {\it - A program to simulate STM images and STS spectra -}}


\vspace{3cm}

{\Large Pablo Ordej\'on}
\vspace{1cm}
{\Large Nicolas Lorente}
\vspace{1cm}
{\Large Alberto Garcia}
\vspace{7mm}
\end{center}

\end{titlepage}

% END TITLE PAGE --------------------------------------------------------------

\tableofcontents

\newpage



\section{INTRODUCTION}

The program {\sc WFS2LDOS} calculates information for STM images or STS
analysis using wavefunctions and other information generated by {\sc
  Siesta}.  It is included among the utilities distributed with {\sc
  Siesta} and it shares several of its basis routines.  {\sc WFS2LDOS} was
written using basic routines from {\sc Siesta} and from {\sc Denchar}.

The code calculates the charge density (actually, the local density of
states (LDOS), which is the charge density generated by wavefunctions
in a given energy window) of the surface on a grid in real space,
defined by the user. The STM images in the Tersoff-Hamann
approximation correspond to maps of the calculated LDOS.
The results are printed in the grid-file format used by {\sc Siesta},
a  binary file with the same format as the RHO, LDOS, etc. files of
{\sc Siesta}. The program streams through the wave-function file,
without the need to keep all the wavefunctions in memory.

The grid in this file is {\bf not} the one used in the {\sc Siesta}
calculation, but the one defined by the user in the {\sc WFS2LDOS} input
file (see below).  This file can be visualized by means of the {\sc
  Plrho} code (in Util), or by the WSxM freeware from WSxM Solutions
(a powerful Windows application for data acquisition and processing in
scanning probe microscopy, which can be freely downloaded from
http://www.wsxmsolutions.com/. It might be possible to make it run on
MacOS through the Wine emulator).  It can also be converted to a
Gaussian Cube format file by the use of the 'g2c\_ng' program in
Util/Grid. Files in Cube format can be visualized by means of standard
programs such as {\sc Vesta}, {\sc Moldel} and {\sc Molekel}.

2D sections of the information contained in the file can be obtained
with the 'plstm' code. This also offers the possibility of obtaining
spin-projected information, even for non-collinear cases.

In its simplest operation, {\sc WFS2LDOS} uses directly the wavefunctions
generated by {\sc Siesta} for the generation of the LDOS used in the
simulation of the STM images.  In the Tersoff-Hamann approximation,
the STM image corresponds to the value of the ``charge density''
(LDOS) (within the energy window defined by the tip-sample potential)
at the position of the tip.

However, for realistic experimental conditions the tip is relatively
far from the surface. Therefore, the accuracy of the {\sc Siesta}
calculation is not sufficiently good, becasue the basis set is
short-ranged, and also because of other issues common to other
approaches like plane waves (the value of the charge at these
distances is so small that it does not influence the total energy,
which is the quantity minimized in DFT, and therefore the values
obtained are not accurate).

To improve the situation, this code can optionally compute
the values of the wavefunctions generated by {\sc Siesta} on a reference
plane (defined by the user) at a distance sufficiently close to the
surface so that the charge density is correctly represented, and then
{\em extrapolate}
the value of these wavefunctions into the vacuum. This
is done assuming that the potential is already flat at the reference
plane, and using the analytical expressions for the propagation of the
solutions of the Schroedinger equation into vacuum. Therefore, {\bf
  the reference plane must be sufficiently close to the surface so
  that the charge density is large and well described by {\sc Siesta},
  but sufficiently far so that the constant potential approximation is
  approximately satisfied}. In practice, one might need to extrapolate
from a plane that is not really in the completely flat region, since
otherwise the wavefunctions would be too small (or zero).

{\sc WFS2LDOS} needs to perform some Fast Fourier Transforms to
extrapolate the value of the wavefunctions into vacuum.
Currently, routines from the FFTW package are called for this.
If the FFTW suite is not installed in your machines, you
will have to download it (available at http://www.fftw.org
under the GNU General Public License).

\noindent
{\bf Limitations:} {\sc WFS2LDOS} works only for monoclinic cells.
The third lattice vector {\bf must} be in the $z$ direction
and be perpendicular to the other two lattice vectors.

\section{HOW TO COMPILE AND RUN THE PROGRAM}

In this section we give all the steps required to install and run the
program.  We assume that you use UNIX, and that you have not moved the
source of {\sc WFS2LDOS} from $\sim$/siesta/Util/STM/ol-stm/Src.

\subsection{Compilation}

  \begin{itemize}

   \item Change to the directory where the sources of {\sc WFS2LDOS} are:

         {\tt \# cd $\sim$/siesta/Util/STM/ol-stm/Src}

   \item Edit Makefile to add the correct references to the installed
     FFTW library. Alternatively, you might have them in your top-level
     \texttt{arch.make} file.

   \item Make the executable:
         {\tt \# make stm} or
     
         {\tt \# make OBJDIR=YourMainBuildDir stm} if you have
         compiled Siesta in a directory different from Obj.

   \item The program should compile and an executable file called
         stm should be created.

  \end{itemize}

\subsection{Running the code}

 {\sc WFS2LDOS} needs some information that will be supplied by {\sc Siesta}. 
 The first thing we must do is to run {\sc Siesta} for 
 the system we are interested in,
 setting up variable WriteDenchar to true. 
 In this way {\sc Siesta} will generate
 two files called {\it SystemLabel}.PLD and {\it SystemLabel}.DIM
 where information 
 needed to plot the charge density and/or wavefunctions 
 in real space is dumped. You also need to have the files which
 contain the information about the basis set for each species
 in your system: {\it ChemicalSpecies}.ion (one for each
 chemical species), which
 are also generated by  {\sc Siesta}.
 You will also need the file containing the
 wavefunction coefficients {\it SystemLabel}.WFSX. 
 A wavefunction file is obtained
 in the {\sc Siesta} run by defining the wave functions to be
 plotted with the {\bf WaveFuncKPoints} descriptor, or by using the
 {\bf COOP.Write T} fdf option (in this case the
 wavefunctions at all k-points used to sample the BZ during
 self-consistency are included).
 Finally, you need the file containing the Hartree potential on the grid 
 {\it Systemlabel}.VH (printed by {\sc Siesta} using the 
 {\bf SaveElectrostaticPotential} descriptor)
 in order to define the vacuum potential. 
 These files need to be present in the
 directory where {\sc WFS2LDOS} will run.

 You need to link the {\it SystemLabel}.selected.WFSX file (or the
 {\it SystemLabel}.fullBZ.WFSX file) produced by {\sc Siesta} to {\it
   SystemLabel}.WFSX before executing the program. The ``selected''
 qualifier is used in connection with the {\bf WaveFuncKPoints}
 option, and ``fullBZ'' when the {\bf COOP.Write T} option is
 selected.

 In principle you need the whole BZ's worth of wavefunctions (in the
 appropriate energy window), but restricted sets of k-points might be
 used for testing.

 You also need to create an input file for {\sc WFS2LDOS} (let's call
 it {\it stm}.fdf), following the instructions given in Section
 \ref{cap:input}. Then, feed it to {\sc WFS2LDOS} as standard input:

 {\tt \# wfs2ldos < {\it stm}.fdf } 

\section{INPUT DATA FILE}
\label{cap:input} 

The input data file is written in an special format called FDF, developed
by Alberto Garc\'{\i}a and Jos\'e M. Soler (see {\sc Siesta} USER'S GUIDE).
It contains all the parameters needed to specify the details
of the run and to define the plane or coordinates system.
Here is a description of the variables that you can define in your 
{\sc Denchar} input files,
with their data types and default values.

\vspace{5pt}
\subsection{General descriptors}

These options are common for STM and STS operation. The only
difference is in the keyword specifying the number of energy samples
(see below).

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf SystemLabel}] ({\it string}): 
A {\bf single} word (max. 20 characters {\bf without blanks})
containing a nickname of the system, used to name output files. 
{\bf It must be the same that you use when you run {\sc Siesta}!!}

{\it Default value:} siesta

\item[{\bf STM.label}] ({\it string}): 
A {\bf single} word (max. 20 characters {\bf without blanks})
containing a special label for the STM run, to be pasted to the
SystemLabel when creating files.

{\it Default value:} blank

\item[{\bf NumberOfSpecies}] ({\it integer}):
Number of different atomic species in the simulation.
Atoms of the same species, but with a different
pseudopotential or basis set are counted as different species.
Use the same value as in the {\sc Siesta} run.

{\it Default value:} There is no default. You must supply this variable.


\item[{\bf ChemicalSpeciesLabel}] ({\it data block}):
It specifies the different chemical species\index{species} that are present,
assigning them a number for further identification.
Use the same as you did in {\sc Siesta}.

{\it Use:} This block is mandatory.

{\it Default:} No default.
\end{description}


\vspace{5pt}
\subsection{Description of the 3D grid where the charge density is obtained.}

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf STM.DensityUnits}] ({\it string}): 
Character string to specify the units of the charge density in output. 
These can be expressed in three forms:

\begin{itemize}
\item[-] Ele/Bohr**3      : Electrons/bohr**3
\item[-] Ele/Ang**3       : Electrons/angstrom**3
\item[-] Ele/UnitCell     : Electrons/Unit Cell 
\end{itemize}

{\it Default value:} Ele/bohr**3

\item[{\bf STM.NumberPointsX}] ({\it integer}):
 Number of subdivision of the grid in the direction of the 
 first lattice vector. Together
 with {\bf STM.NumberPointsY} and {\bf STM.NumberPointsZ}
 it will define the 
 number of points of the grid to plot the charge density.

{\it Default value:} 50

\item[{\bf STM.NumberPointsY}] ({\it integer}):
 Number of subdivision of the grid in the direction
 of the second lattice vector. Together
 with {\bf STM.NumberPointsX} and {\bf STM.NumberPointsZ}
 it will define the 
 number of points of the grid to plot the charge density.

{\it Default value:} 50

\item[{\bf STM.NumberPointsZ}] ({\it integer}):
 Number of subdivision of the grid in the z-direction (which must be the
 direction of the third lattice vector). Together
 with {\bf STM.NumberPointsX} and {\bf STM.NumberPointsY}
 it defines the 
 number of points of the grid to plot the the charge density.

 Note that, for STS operation, the data file produced might be large
 if more than one plane is used. It is suggested to set this parameter
 to 1 in that case.
 Operation on a single plane is also fine for STM mode.

{\it Default value:} 50


\item[{\bf STM.MinZ}] ({\it real length}):
 Defines the minimum value of the z-component of the 3D grid.

 {\it Default value:} None. Must be defined in input file.

 %%%% Must be larger or equal to {\bf STM.RefZ} (see below).

\item[{\bf STM.MaxZ}] ({\it real length}):
 Defines the maximum value of the z-component of the 3D grid.

If a single plane is requested, STM.MaxZ is not used, and it is
set implicitly to STM.MinZ.

{\it Default value:} None. Must be defined in input file.


\item[{\bf STM.RefZ}] ({\it real length}):
 Defines the z-component position of the reference plane from
 where the wavefunctions will be extrapolated into vacuum.

 The LDOS values for planes below the reference level are obtained
 from the original wavefunctions. Those above the reference level are
 obtained from projected wavefunction values.

{\it Default value:} None. Must be defined in input file.

\item[{\bf STM.VacZ}] ({\it real length}):
 Defines the z-component position of the plane on which the
 zero of the Hartree potential in the vacuum region is taken.
 This should be a position at the center of the vacuum of the slab.
 You might want to check (better: plot) the V(z) values printed in the
 {\tt SystemLabel.v\_ave\_z} file. Similar information can be obtained
 using the experimental {\tt v\_info} program in {\tt Util/Grid}.
 
{\it Default value:} None. Must be defined in input file.

\item[{\bf STM.NumberCellsX}] ({\it integer}):
Defines how many times the unit cell is repeated
in the direction of the first lattice vector.

{\it Default value:} 1

\item[{\bf STM.NumberCellsY}] ({\it integer}):
Defines how many times the unit cell is repeated
in the direction of the second lattice vector.

{\it Default value:} 1

\end{description}

\vspace{5pt}
\subsection{Description of the energy window for STM/STS.}

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf STM.Emin}] ({\it real energy}): 
Lower value of the energy window.

{\it Default value:} -1.0 eV

\item[{\bf STM.Emax}] ({\it real energy}): 
Upper value of the energy window.

{\it Default value:} 1.0 eV

\item[{\bf STS.NumberOfPoints}] ({\it integer}): 
  Number of energy points in the above energy window at which
  to sample the LDOS. If this value is not specified, or if it is 1,
  no STS calculation will be performed

  {\it Default value:} 1  (no STS calculation)

\item[{\bf STS.Broadening}] ({\it real energy}): 
  Standard width of the broadening function.

{\it Default value:} 0.2 eV
  
\item[{\bf STS.Broadener}] ({\it string})
  Kind of broadening function. Not implemented yet.
  Currently only a gaussian function is offered.

{\it Default value:} (``gaussian'')
  

\end{description}



\section{OUTPUT FILES}
\label{cap:output} 

In STM mode, the program produces a file which contains the value
of the charge density (which is actually the ``local density of
states'' integrated over the desired energy window), on the grid
defined by the user. In STS mode, the file uses the ``spin'' dimension
to represent the energy dimension.

\begin{description}
\itemsep 10pt
\parsep 0pt

\item[{\bf {\it SystemLabel}.v\_ave\_z}]: An ASCII file containing the
  V(z) profile of the electrostatic potential. Plotting the
  information in this file is useful to set appropriately {\bf
    STM.Vacz} and {\bf STM.RefZ}.  Similar information can be obtained
  using the experimental {\tt v\_info} program in {\tt Util/Grid}.
  
\item[{\bf {\it SystemLabel}.STM.LDOS}]: In STM mode, it contains the
  value of the LDOS (all relevant spin components) at the grid defined
  by the user, in {\sc Siesta} grid format. Can be plotted using WSxM
  and further processed by the {\tt Util/STM/simple-stm/plstm}
  program.

\item[{\bf {\it SystemLabel}.STS}]: In STS mode, it contains the value
  of the LDOS at the grid defined by the user, for all the energies
  sampled in the energy window, in {\sc Siesta} grid format. It can be
  processed in several ways, but currently there is only a example in
  {\tt Util/STM/simple-stm/plsts}. Only the ``total charge'' spin
  projection (as in the 'q' option of 'plstm') is stored.

\item[{\bf {\it SystemLabel}.STS\_AUX}]: In STS mode, this ASCII auxiliary
  file contains the values of the energies used for sampling.

\end{description}



\section{EXAMPLES}

In directory {\tt $\sim$/siesta/Util/STM/ol-stm/Examples} you will
find two examples: one for a ``benzene molecule'', and another for
a magnetic monolayer of Cr, with spin-orbit interaction.

\end{document}
